home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / MATH / RMATH / MATH.DOC < prev    next >
Text File  |  1990-08-17  |  21KB  |  575 lines
  1. MATH -- a unit of elementary mathematical routines for Turbo
  2.         Pascal versions 4, 5, and 5.5.
  3.  
  4.         Copyright 1990, by J. W. Rider
  5.  
  6. MATH.PAS provides a library of mathematical constants, type
  7. definitions, functions, and procedures for immediate use within
  8. contemporary Turbo Pascal programs (tested with version 5.5).
  9. Routines are provided for the following categories:
  10.  
  11.         Numerical rounding and fractioning:
  12.                 ceil, floor, modf, remf, round2, sgn
  13.  
  14.         Binary operators:
  15.                 atan2, fmod, fdiv, frem, hypot, ipow, iroot,
  16.                 max, min, pow, powi, root, round2
  17.  
  18.         Conditional operators:
  19.                 iif
  20.  
  21.         Polynomial evaluation:
  22.                 poly
  23.  
  24.         Exponential and power-raising functions:
  25.                 exp, exp2, exp10, ipow, iroot, pow, powi, pow10,
  26.                 root, sqrt
  27.  
  28.         Logarithmic functions:
  29.                 ln, log, log2, log10
  30.  
  31.         Circular trigonometric functions and inverses:
  32.                 acos, acosd, asin, asind, atan, atan2, atan2d,
  33.                 atand, cosd, sind, tan, tand
  34.  
  35.         Degree/radian conversions for circular trig:
  36.                 deg2dms, deg2rad, dms2deg, dms2rad, rad2deg,
  37.                 rad2dms
  38.  
  39.         Hyperbolic trigonometric functions and inverses:
  40.                 acosh, asinh, atanh, cosh, sinh, tanh
  41.  
  42.  
  43. Some caveats:
  44.  
  45.         MATH.PAS redefines the following SYSTEM unit functions:
  46.  
  47.                 exp, ln, pi, sqrt
  48.  
  49.         In order to improve performance, none of the MATH
  50. routines perform any range-checking for invalid values.
  51. Generally, this only means that the result returned will be
  52. equally invalid.  However, there are some special values that
  53. WILL result in run-time errors for some of the routines.  Calling
  54. the MATH routines with illegal or improper inputs is strictly at
  55. the programmer's risk.
  56.  
  57.         While many of the MATH.PAS routines have parallels in
  58. Turbo C, there are some exceptions where the behavior could be
  59. astonishingly different. This has to do with how "MOD" should be
  60. interpreted.  In Turbo C, (and, in Turbo Pascal, as well) "MOD"
  61. is considered to be what is left-over after integer division.  In
  62. MATH.PAS, "MOD" is considered to be a mathematical "modulus"
  63. function.  For what it is that is left over after division, the
  64. example of the Ada programming language is followed with the use
  65. of the term "REM" (for "remainder").  If you never try to use the
  66. related functions with negative arguments, you'll never have to
  67. worry about whether the difference is important.
  68.  
  69.  
  70. MATH.PAS constant definitions
  71.  
  72.         These are provided as a programmer convenience.  The
  73. routines in MATH.PAS use many, but not all, of them.  However,
  74. there is no particular need for the application program to refer
  75. to them at all.
  76.  
  77.         CBRT2      the cube root of 2
  78.         CBRT3      the cube root of 3
  79.  
  80.         D2R        the number of radians in one degree of arc
  81.  
  82.         E          base of natural logarithms
  83.  
  84.         LN2        natural logarithm of 2
  85.         LN3        natural logarithm of 3
  86.         LN10       natural logarithm of 10
  87.         LOG2E      1/ln(2)
  88.         LOG10E     1/ln(10)
  89.  
  90.         M2R        the number of radians in one minute of arc
  91.  
  92.         PI         plain ol' round pi -- the ratio of the
  93.                 circumference of a circle to its diameter. (Note:
  94.                 this constant replaces the "pi" function of the
  95.                 SYSTEM unit.)
  96.  
  97.         PI_2       pi/2
  98.         PI_4       pi/4
  99.  
  100.         R1_E       1/e
  101.         R1_PI      1/pi
  102.         R1_SQRTPI  1/sqrt(pi)
  103.         R2_PI      2/pi
  104.         R2_SQRTPI  2/sqrt(pi)
  105.         R2D        number of degrees of arc in a radian
  106.  
  107.         S2R        the number of radians in one second of arc
  108.         SQRPI      this is a square, vice round, pi
  109.         SQRT_2     sqrt(1/2)
  110.         SQRT2      sqrt(2)
  111.         SQRTPI     sqrt(pi) or gamma(1/2)
  112.  
  113.  
  114. MATH.PAS type definitions
  115.  
  116.         Depending upon whether or not MATH.PAS is compiled to do
  117. floating point manipulations in hardware or software, the
  118. routines will return different values.
  119.  
  120.         float = either "real" or "double" depending upon the
  121.                 status of the N option.
  122.  
  123.         xfloat = either "real" or "extended" depending upon the
  124.                  status of the N option.
  125.  
  126.         The "float" type is expected to be the primary storage
  127. mechanism for application programs.  The "xfloat" type is
  128. provided to maximize precision in expressions.  There are only a
  129. few functions where it is important to know the difference.  They
  130. are:
  131.  
  132.         deg2dms -- returns "float" values through the DMS
  133.                    arguments
  134.  
  135.         modf    -- returns a "float" value through one of its
  136.                    arguments
  137.  
  138.         poly    -- expects the polynomial coefficients to be an
  139.                    array of "float"
  140.  
  141.         rad2dms -- returns "float" values through the DMS
  142.                    arguments
  143.  
  144.         remf    -- returns a "float" value through one of its
  145.                    arguments
  146.  
  147. (Because of Turbo Pascal's strong type-checking, you may run into
  148. an occasional problem where you've declared a "real" or "double"
  149. variable -- or you're redefined "float" in another unit -- and
  150. can't pass the variable to one of the above routines.  In those
  151. cases, you should be able to do variable type-casting --
  152. "math.float(x)" to bypass the type-checking.  This should be done
  153. with care.)
  154.  
  155. For programmer convenience, MATH.PAS defines a structured type
  156. called "floatray" which is the largest array that can hold
  157. elements of type "float" (as defined above).  There is normally
  158. no need to refer to "floatray" in application programs.
  159.  
  160.  
  161. MATH.PAS function and procedure definitions
  162.  
  163. name    (parameter list)                           type of result
  164. ----    ----------------                           --------------
  165. acos    (x: xfloat)                                     xfloat
  166.  
  167.         Return the principal value of the inverse circular cosine
  168.         of "x" for abs(x)<=1.  The returned value is in radians
  169.         and ranges between 0 and PI.  Related functions:
  170.         "acosd","asin", "atan", "system.cos".
  171.  
  172.  
  173. acosd   (x: xfloat)                                     xfloat
  174.  
  175.         Returns the principal value of the inverse circular
  176.         cosine of "x" for abs(x)<=1.  The returned value is in
  177.         decimal degrees and ranges between 0 and 180. Related
  178.         functions: "acos", "cosd".
  179.  
  180. acosh   (x: xfloat)                                     xfloat
  181.  
  182.         Returns the principal value of the inverse hyperbolic
  183.         cosine of "x" for x>=1.  The returned value is greater
  184.         than or equal to 0. Related functions: "asinh", "atanh",
  185.         "cosh".
  186.  
  187.  
  188. asin    (x: xfloat)                                     xfloat
  189.  
  190.         Returns the principal value of the inverse circular sine
  191.         of "x" for abs(x)<=1.  The returned value is in radians
  192.         and ranges between -PI/2 and +PI/2.  Related functions:
  193.         "acos", "asind", "atan", "system.sin".
  194.  
  195.  
  196. asind   (x: xfloat)                                     xfloat
  197.  
  198.         Returns the principal value of the inverse circular sine
  199.         of "x" for abs(x)<=1.  The returned value is in decimal
  200.         degrees and ranges between -90 and +90.  Related
  201.         functions: "asin", "sind".
  202.  
  203.  
  204. asinh   (x: xfloat)                                     xfloat
  205.  
  206.         Returns the inverse hyperbolic sine of "x".  Related
  207.         functions: "acosh", "atanh", "sinh".
  208.  
  209.  
  210. atan    (x: xfloat)                                     xfloat
  211.  
  212.         Returns the principal value of the inverse circular
  213.         tangent of "x".  The returned value is in radians and
  214.         ranges between -PI/2 and +PI/2.  Note: this is the same
  215.         as "arctan" in the SYSTEM unit.  This function is
  216.         provided for nomenclature consistency only. Related
  217.         functions: "acos", "asin", "atan2", "tan".
  218.  
  219.  
  220. atan2   (x, y: xfloat)                                  xfloat
  221.  
  222.         Returns the angle, in radians, between the x-axis and the
  223.         line segment connecting the origin and the coordinate
  224.         (x,y).  This is the angular component generated in
  225.         converting from cartesian coordinates (x,y) to polar.
  226.         The range of ATAN2 is bounded between -PI and +PI
  227.         radians.  Related functions: "atan", "hypot", "tan".
  228.  
  229.  
  230. atan2d  (x, y: xfloat)                                  xfloat
  231.  
  232.         Returns the angle, in decimal degrees, between the x-axis
  233.         and the line segment connecting the origin and the
  234.         coordinate (x,y).  This is the angular component
  235.         generated in converting from cartesian coordinates (x,y)
  236.         to polar. The range of ATAN2D is bounded between -180 and
  237.         +180 degrees.  Related functions: "atan2", "tand".
  238.  
  239.  
  240. atand   (x: xfloat)                                     xfloat
  241.  
  242.         Returns the principal value of the inverse circular
  243.         tangent of "x".  The returned value is in decimal
  244.         degrees, and ranges between -90 and +90. Related
  245.         functions: "system.arctan", "tand".
  246.  
  247.  
  248. atanh   (x: xfloat)                                     xfloat
  249.  
  250.         Returns the inverse hyperbolic tangent of "x" for
  251.         abs(x)<1.  Related functions: "acosh", "asinh", "tanh".
  252.  
  253.  
  254. ceil    (x: xfloat)                                     xfloat
  255.  
  256.         Returns the smallest integer value greater than or equal
  257.         to "x".  (Rounds up.)  Related functions: "floor" (rounds
  258.         down), "system.int" (rounds toward zero), "system.round"
  259.         (rounds to nearest integer), "round2" (rounds to
  260.         specified number of decimal places).
  261.  
  262.  
  263. cosd    (x: xfloat)                                     xfloat
  264.  
  265.         Returns the circular cosine of "x" degrees.  COSD ranges
  266.         between -1 and +1.  Related functions: "acosd",
  267.         "system.cos".
  268.  
  269.  
  270. cosh    (x: xfloat)                                     xfloat
  271.  
  272.         Returns the hyperbolic cosine of "x".  The returned value
  273.         is greater than or equal to 0.  Related functions:
  274.         "acosh", "sinh", "tanh".
  275.  
  276.  
  277. deg2dms (deg: xfloat; var d,m,s :float)                 ------
  278.  
  279.         Converts "deg" degrees into degree-minute-second
  280.         notation.  Related functions: "deg2rad", "dms2deg".
  281.  
  282.  
  283. deg2rad (x: xfloat)                                     xfloat
  284.  
  285.         Converts "x" degrees into radians.  Related functions:
  286.         "deg2dms", "rad2deg".
  287.  
  288.  
  289. dms2deg (d,m,s: xfloat)                                 xfloat
  290.  
  291.         Converts degrees-minute-seconds into decimals degrees.
  292.         Related functions: "deg2dms", "dms2rad".
  293.  
  294.  
  295. dms2rad (d,m,s: xfloat)                                 xfloat
  296.  
  297.         Converts degrees-minute-seconds into decimals radians.
  298.         Related functions: "rad2dms", "dms2deg".
  299.  
  300.  
  301. exp     (x: xfloat)                                     xfloat
  302.  
  303.         Returns the value of "e" (the base of the natural
  304.         logarithms) raised to the "x" power.  If x is
  305.         sufficiently negative, merely returns 0.  Otherwise, it
  306.         calls "system.exp".  Note: this function is provided as a
  307.         replacement for the "exp" of the SYSTEM unit which
  308.         overflows (!) when "x" is very negative.  Related
  309.         functions: "system.exp", "exp2", "exp10", "math.ln",
  310.         "pow", "root".
  311.  
  312.  
  313. exp2    (x: xfloat)                                     xfloat
  314.  
  315.         Returns the value of "2" raised to the "x" power.
  316.         Related functions: "math.exp", "exp10", "log2".
  317.  
  318.  
  319. exp10   (x: xfloat)                                     xfloat
  320.  
  321.         Returns the value of "10" raised to the "x" power.
  322.         Related functions: "math.exp", "exp2", "log10", "pow10".
  323.  
  324.  
  325. deg2rad (x:xfloat)                                      xfloat
  326.  
  327.         Converts "x" degrees into radians.  Related functions:
  328.         "deg2dms", "rad2deg".
  329.  
  330.  
  331. fdiv    (x, y: xfloat)                                  xfloat
  332.  
  333.         Returns the number of times that "y" divides evenly into
  334.         "x" (rounds toward 0) -- a floating point analogue of the
  335.         integer "DIV" operator.  Related functions: "fmod",
  336.         "frem", "remf".
  337.  
  338.  
  339. floor   (x: xfloat)                                     xfloat
  340.  
  341.         Returns the largest integer value less than or equal to
  342.         "x". (Rounds down.)  Related functions: "ceil" (rounds
  343.         up), "system.int" (rounds toward zero), "system.round"
  344.         (rounds toward nearest integer), "round2" (rounds to
  345.         specified number of decimal places).
  346.  
  347.  
  348. fmod    (x, y: xfloat)                                  xfloat
  349.  
  350.         Returns the modulus that results from evenly dividing "y"
  351.         into "x" (rounded down).  For constant "y", "fmod" is a
  352.         periodic function of "x".  (This is NOT the same as Turbo
  353.         C's "fmod" nor Turbo Pascal's MOD operator for integers!)
  354.         Related functions: "frem", "modf".
  355.  
  356.  
  357. frem    (x, y: xfloat)                                  xfloat
  358.  
  359.         Returns the remainder that results after evenly dividing
  360.         "y" into "x" (rounded toward 0).  For constant "y",
  361.         "frem" is an odd function of "x". A floating point
  362.         analogue of the integer MOD operator.) Related functions:
  363.         "fdiv", "fmod", "remf".
  364.  
  365.  
  366. hypot   (x, y: xfloat)                                  xfloat
  367.  
  368.         Returns the hypoteneuse of the right triangle with sides
  369.         "x" and "y".  This is the range component generated in
  370.         converting cartesian coordinates (x,y) to polar
  371.         coordinates.  Related functions: "atan2".
  372.  
  373.  
  374. iif     (p: boolean; t, f: xfloat)                      xfloat
  375.  
  376.         Returns "t" if "p" is true; otherwise returns "f".  Note:
  377.         this routine will force the unnecessary evaluation of
  378.         either "t" or "f" expressions without regard to which
  379.         value is returned.  It works more efficiently if "t" and
  380.         "f" are variables vice expressions.  This function is
  381.         used within several places in the source code where that
  382.         situation arises.
  383.  
  384.  
  385. ipow    (x, y: xfloat)                                  xfloat
  386.  
  387.         Returns the imaginary component of the complex value that
  388.         results when real "x" is raised the real "y" power. (Function
  389.         "pow" returns the real component.)  There may be an
  390.         infinite number of satisfactory values, and this function
  391.         only returns one.  Related functions: "iroot", "pow".
  392.  
  393.  
  394. iroot   (x, y: xfloat)                                  xfloat
  395.  
  396.         Returns the imaginary component of the complex value that
  397.         results when taking the real "y" root of the real "x"
  398.         value. (Function "root" returns the real component.)
  399.         There may be an infinite number of satisfactory values,
  400.         and this function only returns one. Related functions:
  401.         "ipow", "root".
  402.  
  403.  
  404. ln      (x: xfloat)                                     xfloat
  405.  
  406.         Returns the natural logarithm of "x".  If x<0, it returns
  407.         the real component of the complex logarithm value.  (The
  408.         imaginary component is "pi".)   Note: a simpler version
  409.         of "ln" exists in the SYSTEM unit.  Related functions:
  410.         "math.exp", "log", "log2", "log10".
  411.  
  412.  
  413. log     (x: xfloat)                                     xfloat
  414.  
  415.         Returns the natural logarithm of "x".  Related functions:
  416.         "math.ln", "log2", "log10".
  417.  
  418.  
  419. log2    (x: xfloat)                                     xfloat
  420.  
  421.         Returns the base two logarithm of "x". (Base two
  422.         logarithms are used extensively in information theory.)
  423.         Related functions:  "exp2", "math.ln", "log", "log10".
  424.  
  425.  
  426. log10   (x: xfloat)                                     xfloat
  427.  
  428.         Returns the common or base ten logarithm of "x".  Related
  429.         functions: "exp10", "math.ln", "log", "log2", "pow10".
  430.  
  431.  
  432. max     (x, y: xfloat)                                  xfloat
  433.  
  434.         Returns either "x" or "y", whichever is greater.  Related
  435.         functions: "min".
  436.  
  437.  
  438. min     (x, y: xfloat)                                  xfloat
  439.  
  440.         Returns either "x" or "y", whichever is less. Related
  441.         functions: "max".
  442.  
  443.  
  444. modf    (x: xfloat; var ipart: float)                   xfloat
  445.  
  446.         Divides the value of "x" into an integer part and a
  447.         fractional part.  The integer part (rounded down --
  448.         making it different from Turbo C's "modf" and Turbo
  449.         Pascal's integer MOD operator) is returned in "ipart".
  450.         The fractional part is return as the value of the
  451.         function. Related functions: "fmod", "remf".
  452.  
  453.  
  454. poly    (x: xfloat; degree: integer; var coeffs )       xfloat
  455.  
  456.         Returns the evaluation of the polynomial
  457.  
  458.                                      2                     degree
  459.     coeffs[0]+coeffs[1]*X+coeffs[2]*X +...+coeffs[degree]*X
  460.  
  461.         IMPORTANT! The untyped var "coeffs" is presumed to be an
  462.         array of "float", but the compiler does not enforce this
  463.         restriction.  Passing any other structure to "poly" will
  464.         generate inexplicable results.
  465.  
  466.  
  467. pow     (x, y: xfloat)                                  xfloat
  468.  
  469.         Returns "x" raised the "y" power.  Uses an exponential -
  470.         logarithm algorithm.  Related functions: "math.exp",
  471.         "ipow", "powi", "root", "system.sqr".
  472.  
  473.  
  474. pow10   (x: xfloat)                                     xfloat
  475.  
  476.         Returns ten raised to the "x" power.  Same thing as
  477.         "exp10".  This function is provided for certain
  478.         programmers who are accustomed to exponentiating "10"
  479.         with a function of this name.
  480.  
  481.  
  482. powi    (x: xfloat; n: integer)                         xfloat
  483.  
  484.         Returns "x" raised to the "n" power.  Uses a recursive
  485.         squaring - multiplication algorithm.  Related functions:
  486.         "pow", "system.sqr".
  487.  
  488.  
  489. rad2deg (x: xfloat)                                     xfloat
  490.  
  491.         Converts "x" radians into degrees.  Related functions:
  492.         "deg2rad".
  493.  
  494.  
  495. rad2dms (r:xfloat; var d,m,s: float)                    ------
  496.  
  497.         Converts "r" radians into degrees-minute-seconds. Related
  498.         functions: "dms2rad", "rad2deg".
  499.  
  500.  
  501. remf    (x: xfloat; var ipart: float)                   xfloat
  502.  
  503.         Divides the value of "x" into an integer part and a
  504.         fractional part.  The integer part (rounded toward 0) is
  505.         returned in "ipart".  The fractional part is return as
  506.         the value of the function.  Related functions: "fdiv",
  507.         "frem", "modf". For an example of use, see the source
  508.         code for the procedure "deg2dms".
  509.  
  510.  
  511. root    (x, y: xfloat)                                  xfloat
  512.  
  513.         Returns "x" raised to the "y" power.  If x<0, then the
  514.         real component of the complex power is returned.  Related
  515.         functions: "pow", "system.sqrt".
  516.  
  517.  
  518. round2  (x: xfloat; n: shortint)                        xfloat
  519.  
  520.         Returns "x", rounded to "n" decimal places to the right
  521.         of the decimal point.  If "n" is negative, rounding
  522.         occurs to the left of the decimal point.  NOTE!  Because
  523.         of the approximate nature of storing fractional
  524.         components in floating point representations, you should
  525.         be never assume that the result of "round2" is *exact*.
  526.         However, it should be very, very close.
  527.  
  528.  
  529. sgn     (x: xfloat)                                     xfloat
  530.  
  531.         Returns the "signum" of "x".  If x>0, then "+1" is
  532.         returned.  If x<0, "-1" is returned.  If x=0, then "0"
  533.         is returned.  Related functions: "system.abs".
  534.  
  535.  
  536. sind    (x: xfloat)                                     xfloat
  537.  
  538.         Returns the circular sine of "x" degrees.  SIND ranges
  539.         from -1 to +1.  Related functions: "asind", "system.sin".
  540.  
  541.  
  542. sinh    (x: xfloat)                                     xfloat
  543.  
  544.         Returns the hyperbolic sine of "x".  Related functions:
  545.         "asinh", "cosh", "tanh".
  546.  
  547.  
  548. sqrt    (x: xfloat)                                     xfloat
  549.  
  550.         Returns the square root of "x".  If x>=0, then
  551.         SYSTEM.SQRT is invoked.  For x<0, this function returns
  552.         the negative of system.sqrt(-x).  This makes "math.sqrt"
  553.         an odd function.  Also, note that "math.sqrt(-1) <>
  554.         root(-1,2)".  Instead, "math.sqrt(-1) = -iroot(-1,2)".
  555.         Related functions: "root", "system.sqr", "system.sqrt".
  556.  
  557.  
  558. tan     (x: xfloat)                                     xfloat
  559.  
  560.         Returns the circular tangent of "x".  The value of "x" is
  561.         assumed to be expressed in radians.  Related functions:
  562.         "system.sin", "system.cos", "system.arctan".
  563.  
  564.  
  565. tand    (x: xfloat)                                     xfloat
  566.  
  567.         Returns the circular tangent of "x" degrees. Related
  568.         functions: "atand", "tan".
  569.  
  570.  
  571. tanh    (x: xfloat)                                     xfloat
  572.  
  573.         Returns the hyperbolic tangent of "x".  TANH ranges from
  574.         -1 to 1.  Related functions:  "atanh", "cosh", "sinh".
  575.